Loading and Managing Data

Projects and Workspaces

A project is the most basic format in eCognition Architect. A project contains one or more maps and optionally a related rule set. Projects can be saved separately as a .dpr project file, but one or more projects can also be stored as part of a workspace.

For more advanced applications, workspaces reference the values of exported results and hold processing information such as import and export templates, the required ruleware, processing states, and the required software configuration. A workspace is saved as a set of files that are referenced by a .dpj file.

Creating a Simple Project

To create a simple project go to File > Load Image File.

In the Load Image File(s) dialog box you can:

1. Select multiple files by holding down the Shift or Ctrl keys.
2. Access a list of recently accessed folders displays in the Go to Folder drop-down list. You can also paste a file path into this field (which will also update the folder buttons at the top of the dialog box).

To later add additional image or thematic layers go to File > Add Data Layer in the main menu.

When loading a rule set into a project, multiple layer aliases might refer to the same physical image channel. This happens when the names of the image layers in the ruleset differ from the names introduced when loading the data. In this case, the View Settings window will display only the layer aliases loaded from the rule set. To avoid such situations, please try to keep consistency in the naming of the image channels.

Creating a Project using the Source View dialog

The Source View dialog provides users a simple data management area to modify input layer alias, display orders and access information on file details.

To open the dialog choose View > Source View.

Select the Add input layer to project button to load data files, alternatively you can select the files in the Windows File Explorer and drag and drop them to the dialog to import them. You can add image layers, vector and point cloud layers to a new or existing project.

Furthermore, eCognition project (.dpr) and workspace (.dpj) files can be added by drag and drop.

This button deletes a selected data layer or a whole project (dependent on selection).

The upper pane of the Source View dialog shows the project name, all data layers loaded, their alias and file paths. On selection of a project file or data file the lower pane shows different details and settings.

If you right click in the upper pane on the project name or a data file you can select one of the following options from the context menu:

• Add New... - add a new data layer
• Delete - delete whole project or data layer (dependent on selection)
• Rename - change the project name or image layer alias or map name easily (dependent on selection) . Alternatively, go to Process > Edit Aliases > Manage Layer Aliases to change image layer, point cloud, and thematic layer aliases in the Image / Point cloud Layer Alias or Thematic Layer Alias tab.
  
• Project Settings - opens the Modify Project dialog to see or change further project settings

 

The lower pane of the Source View dialog shows the following details

A) on selection of a project:

• Coordinate System, Unit, Resolution (Unit), Pixel Size, Project Size, Lower left, Upper right, No Data Value

B)  on selection of a data file:

• image data
  • Type, Name, Location, Size, Lower left, Upper right, Unit, Resolution, Data type, No Data Value
• point cloud data
  • Type, Name, Location, Size, Lower left, Upper right, Unit, Resolution, Data type, Number of points, No Data Value
• vector data
  • Type, Name, Location, Attribute table, Size, Lower left, Upper right, Unit, Resolution, Point size for rasterization

 

Use this option to add new maps to your project. Once you have added new maps, you can switch between their properties using the tabs at the bottom of this dialog.

Creating a Project with Predefined Settings

When you create a new project, the software generates a main map representing the image data of a scene. To prepare this, you select image layers and optional data sources like thematic layers or metadata for loading to a new project. You can rearrange the image layers, select a subset of the image or modify the project default settings. In addition, you can add metadata.

An image file contains one or more image layers. For example, an RGB image file contains three image layers, which are displayed through the Red, Green and Blue channels (layers).

Open the Create Project dialog box by going to File > New Project (for more detailed information on creating a project, refer to The Create Project Dialog Box). The Import Image Layers dialog box opens. Select the image data you wish to import, then press the Open button to display the Create Project dialog box.

File Formats

Opening certain file formats or structures requires you to select the correct driver in the File Type drop-down list.

Then select from the main file in the files area. If you select a repository file (archive file), another Import Image Layers dialog box opens, where you can select from the contained files. Press Open to display the Create Project dialog box.

The Create Project Dialog Box

The Create Project dialog box gives you several options. These options can be edited at any time by selecting File > Modify Open Project:

• Change the name of your project in the Project Name field. The Map selection is not active here, but can be changed in the Modify Project dialog box after project creation is finished.
• If you want to rescale the scene during import, edit the scale factor in the text box corresponding to the scaling method used: Resolution (m/pxl), magnification (x), percent (%), or pixel (pxl/pxl).
• To use the geocoding information from an image file to be imported, select the Use geocoding checkbox.
• For feature calculations, value display, and export, you can edit the Pixels size (unit). If you keep the default (auto) the unit conversion is applied according to the unit of the coordinate system of the image data as follows:
  • If geocoding information is included, the pixel size is equal to the resolution.
  • In other cases, pixel size is 1.

In special cases you may want to ignore the unit information from the included geocoding information. To do so, deactivate Initialize Unit Conversion from Input File item in Tools > Options in the main menu

• The Image Layer pane allows you to insert, remove and edit image layers. The order of layers can be changed using the up and down arrows
  • If you use multidimensional image data sets, you can check and edit multidimensional map parameters (see Editing Multidimensional Map Parameters) .
  • If you load two-dimensional image data, you can set the value of those pixels that are not to be analyzed. Select an image layer and click the No Data button to open the Assign No Data Values dialog box.
  • If you import image layers of different sizes, the largest image layer dimensions determine the size of the scene. When importing without using geocoding, the smaller image layers keep their size if the Enforce Fitting check box is cleared. If you want to stretch the smaller image layers to the scene size, select the Enforce Fitting checkbox.
• Thematic layers can be inserted, removed and edited in the same manner as image layers.
• If not done automatically, you can load Metadata source files to make them available within the map.

To define a subset in two-dimensional (2D) image data load the full scene into your workspace:

• Import the full extent of your data into a project (Create a new workspace (File > New Workspace) select File > Create new project). Then in the right pane of the Workspace window select Open subset. Now the Subset Selection dialog appears where you can draw a rectangular subset.

• Activate the Data management layout so that the workspace window is opened and its small toolbar appears:

  

  In this toolbar select Define Rectangular Subset and then the Save subset to a workspace button. (Alternatively you can select the Define Polygonal Subset to draw a polygon for subset selection.)

• Use the algorithm Create Scene Subset in the process tree.

• Use the algorithm Copy map in the process tree (select Source region > create new variable).

To define a subset in 3D data please refer to chapter User Guide > Working with Point Cloud Data

Geocoding and Projection

Geocoding

Geocoding is the assignment of positioning marks in images by coordinates. Typically, available geocoding information is automatically detected: if not, you can enter coordinates manually. Images without geocodes create automatically a virtual coordinate system with a value of 0/0 at the upper left and a unit of 1 pixel. For such images, geocoding represents the pixel coordinates instead of geographic coordinates.

eCognition can reproject raster image layers and vector layers. If the coordinate system is supported, coordinates from inserted files are detected automatically. If the information is not included in the image file but is nevertheless available, you can edit it manually.

After importing a layer in the Create New Project or Modify Existing Project dialog boxes, double-click on a layer to open the Layer Properties dialog box. To edit geocoding information, select the Geocoding check box. You can edit the following:

• x coordinate of the lower left corner of the image
• y coordinate of the lower left corner of the image
• Pixel size defining the geometric resolution

Please find eCognition's projection and reprojection tools in Tools > Projection > Assign Projection and Tools > Projection > Reproject Data described in User Guide > Tools > Projection and Reprojection.

Assign No-Data Values

No-data values can be assigned to scenes with two dimensions only. This allows you to set the value of pixels that are not to be analyzed. Only no-data-value definitions can be applied to maps that have not yet been analyzed.

No-data values can be assigned to image pixel values (or combinations of values) to save processing time. These areas will not be included in the image analysis. Typical examples for no-data values are bright or dark background areas. The Assign No Data Value dialog box can be accessed when you create or modify a project.

After preloading image layers press the No Data button. The Assign No Data Values dialog box opens:

• Selecting Use Single Value for all Layers (Union) lets you set a single pixel value for all image layers.
• To set individual pixel values for each image layer, select the Use individual Values for Each Layer check box
• Select one or more image layers
• Enter a value for those pixels that are not to be analyzed. Click Assign. For example in the dialog box above, the no data value of Layer 1 is 0.000000. This implies that all pixels of the image layer Layer 1 with a value of zero (i.e. the darkest pixels) are excluded from the analysis. The no data value of Layer 2 is set to 255 in the Value field
• Select Intersection to include those overlapping no data areas only that all image layers have in common
• Select Union to include the no data areas of all individual image layers for the whole scene, that is if a no data value is found in one image layer, this area is treated as no data in all other image layers too

Importing Image Layers of Different Scales

You can insert image layers and thematic layers with different resolutions (scales) into a map. They need not have the same number of columns and rows. To combine image layers of different resolutions (scales), the images with the lower resolution – having a larger pixel size – are resampled to the size of the smallest pixel size. If the layers have exactly the same size and geographical position, then geocoding is not necessary for the resampling of images.

Editing Multidimensional Map Parameters

When creating a new map, you can check and edit parameters of multidimensional maps that represent time series. Typically, these parameters are taken automatically from the image data set and this display is for checking only. However in special cases you may want to change the number, the distance and the starting item of frames. The preconditions for amending these values are:

• The project includes at least two frames.
• The new project has not yet been created or the new map has not yet been saved.
• For changing Frame parameters of time series maps, the width of the internal map has to be five times larger or more than the height.

To open the edit multidimensional map parameters, create a new project or add a map to an existing one. After preloading image layers press the Edit button. The Layer Properties dialog box opens.

• Change Frame parameters only to change the time dimension of a time series map.

Editable parameters are listed in the following table - Multidimensional Map Parameters:

Parameter	Description	Calc button	Default
Number of frames	The number of two-dimensional images each representing a single film picture (frame) of a scene with time dimension.	Click the Calc button to calculate the rounded ratio of width and height of the internal map.	1
Frame distance	Change the temporal distance between frames.	(no influence)	1
Frame start	Change the number of the first displayed frame.	(no influence)	0

Confirm with OK and return to the previous dialog box. After the a with a new map has been created or saved, the parameters of multidimensional maps cannot be changed any more.

Multisource Data Fusion

If the loaded image files are geo-referenced to one single coordinate system, image layers and thematic layers with a different geographical coverage, size, or resolution can be inserted.

This means that image data and thematic data of various origins can be used simultaneously. The different information channels can be brought into a reasonable relationship to each other.

 

Using Metadata and Features

Using Metadata and Features

Many image data formats include metadata or come with separate metadata files, which provide additional image information on content, qualitiy or condition of data. To use this metadata information in your image analysis, you can convert it into features and use these features for classification.

The available metadata depends on the data provider or camera used. Examples are:

• data quality information e.g. cloud cover
• time period information of data capture e.g. calender date and time of day
• spatial reference information e.g. values for latitude and longitude

The metadata provided can be displayed in the Object Information window, the Feature View window or the Select Displayed Features dialog box. For example depending on latitude and longitude a rule set for a specific vegetation zone can be applied to the image data.

Manual Metadata Import

Although it is not usually necessary, you may sometimes need to link an open project to its associated meta data file. To add metadata to an open project, go to File > Modify Open Project.

The lowest pane of the Modify Project dialog box allows you to edit the links to metadata files. Select Insert to locate the metadata file. It is very important to select the correct file type when you open the metadata file to avoid error messages.

Once you have selected the file, select the correct field from the Import Metadata box and press OK. The filepath will then appear in the metadata pane.

To populate with metadata, press the Edit button to launch the MetaData Conversion dialog box.

Press Generate All to populate the list with metadata, which will appear in the right-hand column. You can also load or save metadata in the form of XML files.

 

Customized Metadata Import

If you are batch importing large amounts of image data, then you should define metadata via the Customized Import dialog box.

On the Metadata tab of the Customized Import dialog box, you can load Metadata into the projects to be created and thus modify the import template with regard to the following options:

• Add and remove metadata
• Define a special search string for metadata files (for an explanation of search strings, see Editing Search Strings and Scene Names). If the image data contains the metadata, use the default {search-string} expression. If the metadata file is external, this link must be defined.
• Select a format driver to use for importing
• Convert metadata to include it in the feature tree.

A master file must be defined in the Workspace tab; if it is not, you cannot access the Metadata tab. The Metadata tab lists the metadata to be imported in groups and can be modified using the Add Metadata and Remove Metadata buttons.

Populating the Metadata List

You may want to use metadata in your analysis or in writing rule sets. Once the metadata conversion box has been generated, click Load – this will send the metadata values to the Feature View window, creating a new list under Metadata. Right-click on a feature and select Display in Object Information to view their values in the Object Information window.

Data Import

Creating Customized Imports

Multiple scenes from an existing file structure can be imported into a workspace and saved as an import template. The idea is that the user first defines a master file, which functions as a sample file and allows identification of the scenes of the workspace. The user then defines individual data that represents a scene by defining a search string.

A workspace must be in place before scenes can be imported and the file structure of image data to be imported must follow a consistent pattern. To open the Customized Import dialog box, go to the left-hand pane of the Workspace window and right-click a folder to select Customized Import. Alternatively select File > Customized Import from the main menu.

1. Click the Clear button before configuring a new import, to remove any existing settings. Choose a name for your import routine in the Import field. The default name is Customized Import.
2. The Root Folder is the folder where all the image data you want to import will be stored; this folder can also contain data in multiple subfolders. To allow a customized import, the structure of image data storage has to follow a pattern, which you will later define
3. Select a Master File within the root folder or its subfolders. Depending on the file structure of your image data, defined by your image reader or camera, the master file may be a typical image file, a metafile describing the contents of other files, or both.
4. The Search String field displays a textual representation of the sample file path used as a pattern for the searching routine. If you left-click in the Search String field the <Insert Block> drop-down gets active and a variable or block can be added to the string.
5. The Scene Name field displays a representation of the name of the scene that will be used in the workspace window after import. If you left-click in the Scene Name field the <Insert Block> drop-down gets active and a variable or block can be added to the string.
6. Press the Test button to preview the naming result of the Master File based on the Search String

Managing Folders in the Workspace Tree View

Add, move, and rename folders in the tree view on the left pane of the Workspace window. Depending on the import template, these folders may represent different items.

1. To add an item, right-click a folder and select Add [Item].
2. The new folder is displayed in the tree view of the Workspace window. You can edit the folder name. To rename a folder, right-click it and choose Rename on the context menu.
3. Move folders to rearrange them by drag-and-drop operations.

Saving and Moving Workspaces

Workspaces are saved automatically whenever they are changed. If you create one or more copies of a workspace, changes to any of these will result in an update of all copies, irrespective of their location. Moving a workspace is easy because you can move the complete workspace folder and continue working with the workspace in the new location. If file connections related to the input data are lost, the Locate Image dialog box opens, where you can restore them; this automatically updates all other input data files that are stored under the same input root folder. If you have loaded input data from multiple input root folders, you only have to relocate one file per input root folder to update all file connections.

We recommend that you do not move any output files that are stored by default within the workspace folder. These are typically all .dpr project files and by default, all results files. However, if you do, you can modify the path of the output root folder under which all output files are stored.

To modify the path of the output root folder choose File > Workspace Properties from the main menu. Clear the Use Workspace Folder check-box and change the path of the output root folder by editing it, or click the Browse for Folders button and browse to an output root folder. This changes the location where image results and statistics will be stored. The workspace location is not changed.

Opening Projects and Workspace Subsets Open a project to view and investigate its maps in the map view:

1. Go to the right-hand pane of the Workspace window that lists all projects of a workspace.
2. Do one of the following:
   • Right-click a project and choose Open on the context menu.
   • Double-click a project
   • Select a project and press Enter.
3. The project opens and is displayed its main map in the map view. If another project is already open, it is closed before opening the other one. If maps are very large, you can open and investigate a subset of the map:
   • Go to the right pane of the Workspace window that lists all projects of a workspace
   • Right-click a project and choose Open Subset. The Subset Selection dialog box opens
   • Define a subset and confirm with OK. The subset displays in the map view. This subset is not saved with the project and does not modify the project. After closing the map view of the subset, the subset is lost; however, you can save the subset as a separate project.

Inspecting the State of a Project

For monitoring purposes you can view the state of the current version of a project. Go to the right-hand pane of the Workspace window that lists the projects. The state of a current version of a project is displayed behind its name.

Processing States Related to User Workflow
Created	Project has been created.
Canceled	Automated analysis has been canceled by the user.
Edited	Project has been modified automatically or manually.
Processed	Automated analysis has finished successfully.
Skipped	Tile was not selected randomly by the submit scenes for analysis algorithm with parameter Percent of Tiles to Submit defined smaller than 100.
Stitched	Stitching after processing has been successfully finished.
Accepted	Result has been marked by the user as accepted.
Rejected	Result has been marked by the user as rejected.
Deleted	Project was removed by the user. This state is visible in the Project History.
Other Processing States
Unavailable	The Job Scheduler (a basic element of eCognition software) where the job was submitted is currently unavailable. It might have been disconnected or restarted.
Waiting	Project is waiting for automated analysis.
Processing	Automated analysis is running.
Failed	Automated analysis has failed. See Remarks column for details.
Timeout	Automated analysis could not be completed due to a timeout.
Crashed	Automated analysis has crashed and could not be completed.

Inspecting the History of a Project

Inspecting older versions helps with testing and optimizing solutions. This is especially helpful when performing a complex analysis, where the user may need to locate and revert to an earlier version.

1. To inspect the history of older project versions, go to the right-hand pane of the Workspace window that lists projects. Right-click a project and choose History from the context menu. The Project History dialog box opens.
2. All project versions (Ver.) are listed with related Time, User, Operations, State, and Remarks.
3. Click OK to close the dialog box.

Clicking a column header lets you sort by column. To open a project version in the map view, select a project version and click View, or double-click a project version.

To restore an older version, choose the version you want to bring back and click the Roll Back button in the Project History dialog box. The restored project version does not replace the current version but adds it to the project version list. The intermediate versions are not lost.

Reverting to a Previous Version

Besides the Roll Back button in the Project History dialog box, you can manually revert to a previous version. (In the event of an unexpected processing failure, the project automatically rolls back to the last workflow state. This operation is documented as Automatic Rollback in the Remarks column of the Workspace window and as Roll Back Operation in the History dialog box.)

1. Do one of the following:
   • Select a project in the right pane of the Workspace window and select Analysis > Rollback All on the main menu
   • Right-click a folder in the left pane of the Workspace window and select Rollback All on the context menu. Alternatively, you can select Analysis > Rollback All on the main menu. The Rollback All Changes dialog box opens.
2. Select Keep the Current State in the History if you want to keep the history when going back to the first version of the projects.

The intermediate versions are not lost. Select Destroy the History and All Results if you want to restart with a new version history after removing all intermediate versions including the results. In the Project History dialog box, the new version one displays Rollback in the Operations column.

Importing an Existing Project into a Workspace

Processed and unprocessed projects can be imported into a workspace.

Go to the left-hand pane of the Workspace window and select a folder. Right-click it and choose Import Existing Project from the context menu. Alternatively, Choose File > New Project from the main menu.

The Open Project dialog box will open. Select one project (file extension .dpr) and click Open; the new project is added to the right-hand Workspace pane.

Creating a New Project Within a Workspace

To add multiple projects to a workspace, use the Import Scenes command. To add an existing projects to a workspace, use the Import Existing Project command. To create a new project separately from a workspace, close the workspace and use the Load Image File or New Project command.

1. To create a new project within a workspace, do one of the following:
   • Go to the left pane of the Workspace window. Right-click a folder and, if available, choose Add Project from the context menu.
   • Choose File > New Project from the main menu.
   • Choose File > Load Image File from the main menu. The Import Image Layers dialog box opens.
2. Proceed in the same way as for creating separate projects.
3. Click OK to create a project. The new project is displayed in the right pane of the Workspace.

Loading Scenes as Maps into a New Project

Multi-map projects can be created from multiple scenes in a workspace. The preconditions to creating these are:

• individual scenes to be loaded must include only one map
• Scenes to be loaded must not have an image object library (the status should be set to cancelled).

In the right-hand pane of the Workspace window select multiple projects by holding down the Ctrl or Shift key. Right-click and select Open from the context menu. Type a name for the new multi-map project in the opening New Multi-Map Project Name dialog box. Click OK to display the new project in the map view and add it to the project list.

If you select projects of different folders by using the List View, the new multi-map project is created in the folder with the last name in the alphabetical order. Example: If you select projects from a folder A and a folder B, the new multi-map project is created in folder B.

Working on Subsets and Copies of Scenes

If you have to analyze projects with maps representing scenes that exceed the processing limitations, you have to consider some preparations.

Projects with maps representing scenes within the processing limitations can be processed normally, but some preparation is recommended if you want to accelerate the image analysis or if the system is running out of memory.

To handle such large scenes, you can work at different scales. If you process two-dimensional scenes, you have additional options:

• Definition of a scene subset
• Tiling and stitching of large scenes
• Tiling of large scenes

For automated image analysis, we recommend developing rule sets that handle the above methods automatically. In the context of workspace automation, subroutines enable you to automate and accelerate the processing, especially the processing of large scenes.

Removing Projects and Deleting Folders

When a project is removed, the related image data is not deleted. To remove one or more projects, select them in the right pane of the Workspace window. Either right-click the item and select Remove or press Del on the keyboard.

To remove folders along with their contained projects, right-click a folder in the left-hand pane of the Workspace window and choose Remove from the context menu.

If you removed a project by mistake, just close the workspace without saving. After reopening the workspace, the deleted projects are restored to the last saved version.

Saving a Workspace List to File

To save the currently displayed project list in the right-hand pane of the Workspace window to a .csv file:

1. Go to the right pane of the Workspace window. Right-click a project and choose Save list to file from the context menu.
2. The list can be opened and analyzed in applications such as Microsoft® Excel.

In the Options dialog box under the Output Format group, you can define the decimal separator and the column delimiter according to your needs.

Copying the Workspace Window

The current display of both panes of the Workspace can be copied the clipboard. It can then be pasted into a document or image editing program for example. Simply right-click in the right or left-hand pane of the Workspace Window and select Copy to Clipboard.

Tutorials

To give you practical illustrations of structuring a rule set into subroutines, have a look at some typical use cases including samples of rule set code. For detailed instructions, see the related instructional sections and the Reference Book listing all settings of algorithms.

Use Case Basic: Create a Scene Subset

Find regions of interest (ROIs), create scene subsets, and submit for further processing.

In this basic use case, you use a subroutine to limit detailed image analysis processing to subsets representing ROIs. The image analysis processes faster because you avoid detailed analysis of other areas.

Commonly, you use this subroutine use case at the beginning of a rule set and therefore it is part of the main process tree on the Main tab. Within the main process tree, you sequence processes in order to find regions of interest (ROI) on a bright background. Let us say that the intermediate results are multiple image objects of a class no_background representing the regions of interest of your image analysis task.

Still editing within the main process tree, you add a process applying the create scene subset algorithm on image objects of the class no_background in order to analyze regions of interest only.

The subsets created must be sent to a subroutine for analysis. Add a process with the algorithm submit scenes for analysis to the end of the main process tree. It executes a subroutine that defines the detailed image analysis processing on a separate tab.

Use Case Advanced: Transfer Results

Transfer intermediate result information by exporting to thematic layers and reloading them to a new scene copy. This subroutine use case presents an alternative for using the merging results parameters of the submit scenes for analysis algorithm because its intersection handling may result in performance intensive operations.

Here you use the export thematic raster files algorithm to export a geocoded thematic layer for each scene or subset containing classification information about intermediate results. This information, stored in a thematic layers and an associated attribute table, is a description of the location of image objects and information about the classification of image objects.

After exporting a geocoded thematic layer for each subset copy, you reload all thematic layers to a new copy of the complete scene. This copy is created using the create scene copy algorithm.

The subset thematic layers are matched correctly to the complete scene copy because they are geocoded. Consequently you have a copy of the complete scene with intermediate result information of preceding subroutines.

Using the submit scenes for analysis algorithm, you finally submit the copy of the complete scene for further processing to a subsequent subroutine. Here you can use the intermediate information of the thematic layer by using thematic attribute features or thematic layer operations algorithms.

Advanced: Transfer Results of Subsets 

'at ROI_Level: export classification to ExportObjectsThematicLayer 

'create scene copy 'MainSceneCopy' 

'process 'MainSceneCopy*' subsets with 'Further' 

Further 

'Further Processing 

''...

''...

''...